HAL FLASH migration: List of applicable concepts

This section provides information about the HAL FLASH applicable architecture concepts.

In HAL1, the FLASH driver manages Flash memory operations.

In HAL2, depending on the device family, memory operations are managed either by the FLASH driver or by the NVM driver.

For NVM-based families, the NVM driver provides programming services similar to those of FLASH with minor differences:

• There is no erase step for NVM memories.

  • Erase-by-address, page erase, bank erase, and mass erase remain FLASH-specific.

  • For NVM-based families, the only erase service that may be exposed is OBK erase, when that feature exists.

In this migration guide, when a concept exists in both HAL2 FLASH and HAL2 NVM, the migration is illustrated using the HAL2 FLASH name. The same naming rule applies to HAL2 NVM.

Concepts for FLASH

Concept	Description
Fully rework HAL Flash driver APIs.	Rework the HAL FLASH driver APIs to improve modularity and flexibility. The driver HAL FLASH has been split into two set of files: hal_flash.c: provides APIs for FLASH programming and erase operations. hal_flash_itf.c: provides APIs for FLASH control, configuration, and option bytes management. Regarding erasing and programming’s APIs, allowing programming a full buffer instead of a single flash word: Programming by address (also applicable to NVM-based families). Erasing by address (FLASH only). Erasing by page (FLASH only). Erasing banks (FLASH only). Performing a full FLASH erase (FLASH only, for NVM-based families, only OBK mass erase may be available). Callback registration capabilities for programming and erase operations have been added. APIs to retrieve FLASH organization and size information have been provided. Note All control and feature APIs such as lock/unlock, prefetch, ECC enable/disable, and option bytes management are handled separately in the hal_flash_itf.h/c. Option bytes are also managed on the ITF side using dedicated APIs, as these are one-shot operations not based on the handle.
Separation of initialization and configuration functions	There is no init or configuration functions needed in HAL1. In HAL2 the HAL FLASH driver has been fully reworked: A handle has been introduced HAL_FLASH_Init `` initialization function and the ``HAL_FLASH_SetProgrammingMode configuration function have been provided. Process functions using the handle and based on buffer for programming and erasing have been provided.
Renaming of the handle structure	New HAL handle hal_flash_handle_t have been introduced.
Unitary configuration APIs	New configuration APIs are available to set FLASH features.
Introduction of HAL user data set/get APIs	Set/Get User Data functions HAL_FLASH_SetUserData and HAL_FLASH_GetUserData for the FLASH peripheral have been provided.
Individual callback registration APIs replace global register and unregister functions	The callback registration is handled by specific functions for each FLASH event. These functions are used to register callback functions for different FLASH events.
Introduce specialized IRQ handlers	Global HAL_FLASH_IRQHandler still available and we provide . In addition, new process-specific handlers HAL_FLASH_<PROCESS>_IRQHandler are provided for handling individual processes separately. HAL_FLASH_ProgramByAddr_IRQHandler() specific to FLASH program operations (also applicable to NVM-based families). HAL_FLASH_EraseByAddr_IRQHandler() specific to FLASH erase by address operation. (FLASH only) HAL_FLASH_ErasePage_IRQHandler() specific to FLASH erase by page operation. (FLASH only) HAL_FLASH_EraseBank_IRQHandler() specific to FLASH erase bank operation. (FLASH only) HAL_FLASH_MassErase_IRQHandler() specific to FLASH mass erase (FLASH only, for NVM-based families, only OBK mass erase may be available). Note All the above IRQ handlers are dedicated to FLASH IO operations. Additionally, there is a separate IRQ handler named HAL_FLASH_ITF_IRQHandler() specifically dedicated to managing errors on the FLASH ITF.
HAL implementation with LL inline functions	HAL FLASH APIs now rely on LL APIs rather than performing direct register access.
Define statements and enumerations redirected to LL equivalents	HAL FLASH define statements and enumerations are based on LL define statements.
Removal of hardware-related macros in HAL2	All hardware macros have been removed from the HAL FLASH driver, and equivalent services are ensured through the LL APIs.
Revised and optimized HAL state machine	The FLASH IO is now managed by three states: HAL_FLASH_STATE_RESET HAL_FLASH_STATE_IDLE HAL_FLASH_STATE_ACTIVE Note There is no state machine implemented for the FLASH ITF driver.
Revised and optimized HAL API status returns	The HAL FLASH functions were updated to return: HAL_INVALID_PARAM: in case of a NULL p_config structure pointer. HAL_ERROR: in case of an error. HAL_TIMEOUT: in case of a user timeout. HAL_BUSY: in case of an ongoing process. HAL_OK: in case of a successfully completed operation.
Revised and optimized HAL error management	Redesigned error handling mechanisms within HAL to improve detection, reporting, and handling of errors, providing more detailed and consistent error codes.
Replaced TypeDef suffix with _t in type names	All TypeDef parts of the HAL FLASH driver have been removed and replaced by _t.
Replaced nonmodifiable pointers with const keywords	Const keywords have been added to non-modifiable pointers to ensure that either the pointer itself or the data it points to cannot be modified. This enhances code safety and readability, prevents unintended modifications, and renders code more robust and maintainable.
Refactor the HAL inclusion model.	Updated HAL inclusion mechanism to improve modularity and reduce compilation dependencies.
Merge HAL extension files with common ones and remove the EX prefix from APIs.	Only one HAL FLASH header file remains and all macros, define statements, and functions from hal_flash_ex.h have been moved to hal_flash.h.
Rework the HAL Flash Driver APIs to use a handle object.	Improved HAL FLASH driver portability to better support multi-bank handling. Introduced a new FLASH handle structure hal_flash_handle_t to separate initialization and configuration for better flexibility.
Replace Finite Parameter Defines (Including PPP Instances) with Enum Types at HAL Levels.	Finite parameters (including FLASH instances) have been converted into enumerated types (enums) at HAL level. This improves code readability, maintainability, and type safety.
Optimize HAL PPP IRQ Handlers by Reordering Processes and Error Management Statements to Prioritize Critical Interrupts	In HAL2, the implementation of HAL_FLASH_IRQHandler has been improved to prioritize the most critical FLASH I/O operations. The interrupt handling sequence is now organized according to operation importance: programming, erase by address, erase by page, erase by bank, mass erase, and finally ECC error management. This reordered prioritization ensures that critical FLASH operations are serviced first, enhancing both reliability and overall system performance.
Add HAL_PPP Prefix to All HAL Peripheral APIs (Defines, Macros, Types, and Functions).	All HAL FLASH functions now start with HAL_FLASH.

Other HAL FLASH changes

Concept

Consideration

Granularity for secure/non-secure FLASH usage

Provides full granularity for FLASH operations in both secure and non-secure contexts. This enables independent management of FLASH programming and access in the secure world and the non-secure world. For example: HAL_FLASH_ProgramByAddr(hal_flash_handle_t *hflash, uint32_t flash_addr, const uint32_t *p_data, uint32_t size_byte, uint32_t timeout_msec) HAL_FLASH_NS_ProgramByAddr(hal_flash_handle_t *hflash, uint32_t flash_addr, const uint32_t *p_data, uint32_t size_byte, uint32_t timeout_msec)